Workflow Loop Template

The Workflow Loop template demonstrates how a BindAI workflow can repeatedly execute a workflow path while a predicate evaluates to True. A LoopNode evaluates a predicate against the current workflow context. When the predicate is true, execution is directed to the loop body. When it is false, execution is directed to the loop exit. This template introduces iterative workflow execution.

Purpose

This template demonstrates how to:

Add a LoopNode to a workflow
Evaluate a runtime predicate
Execute a loop body repeatedly
Maintain state through the workflow context
Exit the loop when the predicate becomes false
Build iterative workflow automation

Workflow Structure

A LoopNode requires two next nodes:

             +----------------+
             |                |
             v                |
          LoopNode            |
          /      \             |
         /        \            |
        v          v           |
   Loop Body     Exit Node     |
        |                       |
        +-----------------------+

More precisely, the LoopNode interprets its next_nodes as:

next_nodes[0] -> loop body
next_nodes[1] -> exit node

This ordering is part of the current LoopNode implementation.

LoopNode

A loop is created with a node ID and a predicate:

loop = LoopNode(
    "process-loop",
    predicate,
)

The predicate receives the current workflow context:

Callable[[WorkflowContext], bool]

For example:

def should_continue(context):
    return context.variables.get("counter", 0) < 3

The predicate determines whether execution should continue through the loop body or leave the loop.

Configuring the Loop

The loop must have at least two next nodes. The first node is the loop body:

loop.next_nodes[0]

The second node is the exit:

loop.next_nodes[1]

Conceptually:

LoopNode
   |
   +---- next_nodes[0] ---> Body
   |
   +---- next_nodes[1] ---> Exit

If fewer than two next nodes are configured, the loop raises:

LoopNode requires two next nodes (body and exit).

Execution Flow

When the executor reaches the loop, the LoopNode evaluates its predicate.

LoopNode
    |
    v
Evaluate Predicate
    |
    +---- True ----> Loop Body
    |
    └---- False ---> Exit Node

The loop does not directly execute the selected node. Instead, it sets:

context.current_node

to the appropriate node ID. The workflow executor then uses that value to determine the next node to execute.

Loop Predicate

The predicate receives the workflow context. For example:

def should_continue(context):
    counter = context.variables.get("counter", 0)
    return counter < 3

The predicate returns:

True to execute the loop body
False to execute the exit node

The predicate is evaluated each time the LoopNode executes.

Workflow Variables

Loop predicates commonly use workflow variables to track progress. For example:

def should_continue(context):
    return context.variables.get("counter", 0) < 3

A loop body could update the counter:

context.variables["counter"] += 1

The conceptual execution becomes:

counter = 0
     |
     v
  LoopNode
     |
     v
 Body
     |
     | counter = 1
     v
  LoopNode
     |
     v
 Body
     |
     | counter = 2
     v
  LoopNode
     |
     v
 Body
     |
     | counter = 3
     v
  LoopNode
     |
     | predicate == False
     v
 Exit

The actual state changes depend on the nodes used in the workflow.

Basic Example

A simple loop can be structured conceptually as:

def should_continue(context):
    return context.variables.get("counter", 0) < 3


loop = LoopNode(
    "loop",
    should_continue,
)

loop.next_nodes = [
    "process-item",
    "loop-complete",
]

This means:

next_nodes[0] = "process-item"
next_nodes[1] = "loop-complete"

When the predicate returns True, the workflow proceeds to process-item. When the predicate returns False, the workflow proceeds to loop-complete.

Iterative Processing

A loop is useful when a workflow needs to repeatedly process data. For example:

Load Items
    |
    v
Loop
 /  \
v    v
Process  Finished
   |
   v
Update State
   |
   +---------> Loop

The process node can update the workflow context so that the next loop evaluation sees the new state.

Batch Processing

Loops can be used for collection-oriented workflows. Conceptually:

Load Items
    |
    v
Loop
 /   \
v     v
Process Finished
Item
  |
  v
Advance Index
  |
  +-------> Loop

A variable such as an index can determine whether another item remains. For example:

def has_more_items(context):
    index = context.variables.get("index", 0)
    items = context.variables.get("items", [])
    return index < len(items)

The loop body can process the current item and advance the index.

Polling

Loops can also represent repeated checks of runtime state. For example:

Check Status
     |
     v
   Loop
   /  \
  v    v
Check  Finished
Again
  |
  +-------> Loop

The predicate can determine whether the workflow should continue checking. The loop itself does not provide a built-in sleep or delay operation. If waiting between checks is required, that behavior must be provided by the surrounding workflow implementation.

Shared Workflow Context

Each workflow execution operates with a workflow context. The loop predicate receives that context directly:

def predicate(context):
    ...

The loop body can update the same execution state. Conceptually:

Iteration 1
    |
    v
Workflow Context
    |
    v
Iteration 2
    |
    v
Workflow Context
    |
    v
Iteration 3

Variables remain available to later nodes unless they are explicitly changed.

Loop Exit

The loop exits when the predicate returns False.

LoopNode
    |
    v
Predicate
    |
    | False
    v
Exit Node

The exit node is next_nodes[1]. The exit node can then connect to additional workflow nodes. For example:

Loop
 |
 | False
 v
Finalize
 |
 v
Next Workflow Step

There is no special built-in EndNode required for a loop exit.

Loop vs Condition

A condition selects a path once when it executes. A loop can repeatedly evaluate its predicate.

Condition	Loop
Selects a branch	Selects body or exit
Normally evaluates once per visit	Can be revisited repeatedly
Uses true/false branch references	Uses body/exit next-node positions
Decision-oriented	Iteration-oriented

Both use the workflow context to make runtime decisions.

Loop vs Retry

Loops and retries both involve repeated execution, but they serve different purposes.

Loop	Retry
Intentional workflow iteration	Failure recovery
Controlled by a predicate	Triggered by node exceptions
Part of workflow control flow	Managed by the workflow executor
Can process repeated business steps	Repeats a failed node
Uses loop body and exit paths	Uses retry policy

Use a loop when repetition is part of the business process. Use a retry policy when an operation fails and should be attempted again.

Preventing Infinite Loops

A loop should have a predicate that can eventually become false. For example:

def should_continue(context):
    return context.variables.get("counter", 0) < 10

The loop body must update the state used by the predicate:

context.variables["counter"] += 1

Without a state change, a predicate such as:

return context.variables.get("counter", 0) < 10

could remain true indefinitely. A useful pattern is:

Loop
 |
 v
Modify State
 |
 v
Loop
 |
 v
Eventually Predicate == False
 |
 v
Exit

Error Handling

The LoopNode itself raises an error if it does not have two next nodes:

LoopNode requires two next nodes (body and exit).

Errors raised during execution of the loop body are handled by the workflow executor. If no retry policy is configured, the workflow fails. If a retry policy is configured, the executor can retry the failed node according to the configured attempt limit. Loop behavior and retry behavior are separate mechanisms.

Combining Loops with Conditions

Loops and conditions can be combined. For example:

Start
  |
  v
Loop
 /  \
v    v
Process  Finished
  |
  v
Condition
 /      \
Continue Stop
  |        |
  +------> Loop

The exact routing depends on the node relationships configured in the workflow. A condition can be used inside a loop body to make additional decisions.

Combining Loops with Agents

An agent can participate in the loop body when repeated AI processing is required. For example:

Loop
 |
 v
Agent
 |
 v
Update Context
 |
 +-------> Loop

The agent can process information and the surrounding workflow can update context variables before the next loop evaluation. The LoopNode itself does not perform AI operations.

Current Implementation Details

The current implementation has the following behavior:

class LoopNode(WorkflowNode):
    ...

It stores:

self.predicate

During execution it first verifies that two next nodes exist:

if len(self.next_nodes) < 2:
    raise RuntimeError(...)

It then evaluates:

self.predicate(context)

When the predicate is true:

context.current_node = self.next_nodes[0]

When the predicate is false:

context.current_node = self.next_nodes[1]

The WorkflowExecutor subsequently uses context.current_node when determining what node to place into the execution queue.

Important Boundaries

Two next nodes are required

The current implementation requires at least two entries in next_nodes. They represent:

next_nodes[0] -> body
next_nodes[1] -> exit

The predicate receives the context

The loop predicate receives the complete workflow context:

Callable[[WorkflowContext], bool]

It is not passed a single variable automatically.

The loop does not execute its body directly

The loop sets context.current_node. The workflow executor is responsible for continuing execution.

No built-in delay

The LoopNode does not provide a built-in waiting period between iterations. Polling workflows that require delays need another mechanism for waiting.

No automatic iteration counter

The LoopNode does not maintain a built-in iteration counter. If a workflow needs one, store it in the workflow context or another appropriate state mechanism.

Best Practices

Always configure both the loop body and exit node.
Make the predicate deterministic and easy to understand.
Update the state used by the predicate during the loop body.
Ensure the loop has a realistic termination condition.
Keep loop bodies focused.
Use retries for transient failures rather than business-process repetition.
Test both loop continuation and loop exit.
Test edge cases such as an empty collection or an already-satisfied condition.
Avoid unnecessary nested loops.
Add observability for workflows containing long or complex loops.

The loop pattern builds on the basic workflow model introduced in:

08.1 workflow-basic.md

It can be combined with:

08.2 workflow-condition.md
08.4 workflow-parallel.md
08.5 workflow-human.md
08.6 workflow-retry.md
08.7 workflow-timeout.md
08.8 workflow-schedule.md

Summary

The Workflow Loop template introduces iterative execution into BindAI workflows. The essential pattern is:

             +----------------+
             |                |
             v                |
          LoopNode            |
          /      \             |
         /        \            |
        v          v           |
   Loop Body     Exit Node     |
        |                       |
        +-----------------------+

A LoopNode evaluates a predicate against the workflow context. If the predicate returns True, the first configured next node is selected as the loop body. If the predicate returns False, the second configured next node is selected as the loop exit. The workflow executor then continues execution using the selected node. This provides a simple mechanism for repeated business processing, collection handling, polling-style workflows, and other iterative workflow patterns.

​Workflow Loop Template

​Purpose

​Workflow Structure

​LoopNode

​Configuring the Loop

​Execution Flow

​Loop Predicate

​Workflow Variables

​Basic Example

​Iterative Processing

​Batch Processing

​Polling

​Shared Workflow Context

​Loop Exit

​Loop vs Condition

​Loop vs Retry

​Preventing Infinite Loops

​Error Handling

​Combining Loops with Conditions

​Combining Loops with Agents

​Current Implementation Details

​Important Boundaries

​Two next nodes are required

​The predicate receives the context

​The loop does not execute its body directly

​No built-in delay

​No automatic iteration counter

​Best Practices

​Related Templates

​Summary